Command Interface

External commands are very closely tied to the nShell application.  For this reason, the following rules must be followed very carefully.

Interface Rules

The following rules define the nShell external command interface.

File Types

nShell command files have a creator of ‘NSHA’, and a type of ‘NSHC’.

Code Resource Types

The nShell environment supports single-segment code resources.  The code resource for a command should have a type of ‘NSHC’ and a name of "command".

Resource Numbers

With the exception of ‘vers’ resources, all resources within nShell command files have I.D. numbers of 16000 or higher.  See the section called “An Example Command” for more about setting up command resources.

The File “nshc.h” Defines The C Interface

The “main” for nShell commands is defined in nshc.h.  At run time, this main is passed pointers for two parameter blocks, also defined in nshc.h.  The “nshc_calls” block defines the callback interface to the nShell application.  The “nshc_parms” block defines the data available to the command.

Passing Arguments

Three fields within nshc_parms contain arguments to nShell commands:

argc

The number of arguments (including the command itself)

argv

An array of indexes into the command line buffer

arg_buf

The command line buffer

The arg_buf contains a series of null-terminated strings, one for each command argument.  The start of a particular string is arg_buf[ argv[ n ] ], where n is the argument number 0..(argc-1).

The Command Must Accept Start/Continue/Stop Messages From The Application

External commands base their actions upon the “action” scalar within the nshc_parms record:

nsh_idle

do nothing

nsh_start

do part or all

nsh_continue

continue processing

nsh_stop

clean up and exit

The Command Must Give Up Time For Multitasking

Task switches in the nShell environment occur only when a command "returns" to the main application.  If a command requires more than a small amount of time to execute or if it requires keyboard input from the operator, the command should give time back to the application.  In this procedure, a command should set it's action scalar to nsh_continue and return back to the application.  When other tasks have been satisfied the application will again call the command.  The command should then use the action scalar or custom data to determine what internal actions are required.  See the "delay" command for an example.

The Command Must Signal Completion

Whenever a command completes its task, it must set two variables in the nshc_parms data structure.  The ‘action’ scalar must be set to to nsh_idle, and the ‘result’ variable must be set to reflect success or failure ( <0 = error, 0 = success, >0 = non-error return values ).

Data Allocation

Commands allocate storage in two ways:

First, local variables may be defined within each routine.

Secondly, data may be allocated using NewHandle.  Any such data structure must be hung off the “data” handle within nshc_parms.  The command is responsible for disposing of this data before going into an nsh_idle state.